Programming the Automation Model

After you build the automation model graphically, you need to realize the flow of data between the model's elements like ActionTasks and sub-Automations.

Parameter Binding

The full sets of variables or "objects" available to Runbook components are often referred to as "bindings". Each ActionTask in the automation model must define from where the Inputs values are coming and to where the Outputs values are going (if required).
To set input/output values:

1. Select the Element which you want to edit.
2. Select the related Parameter from the list.
3. Click Edit and the Edit Parameter popup window appears.
4. Click From Source to open a pull-down list of parameters.
5. Choose how to bind the Inputs and Outputs variables.
6. Click Update.

Inputs are pre-defined constants or values re-directed from other sources. Well-designed ActionTasks are "context-free", relying on Inputs and Outputs variables to handle data. Whenever possible, set Inputs explicitly. For Inputs, you can select where the parameter value is copied from.

The following table lists the ActionTask input sources.

Type	Description
CONSTANT	Fixed literal value.
OUTPUTS	Variable from a preceding ActionTask, selected from a drop-down list of available Outputs variables.
FLOWS	Variables persisted through a given path (FLOWS variable names must be specified and are case sensitive).
PARAMS	Similar to FLOWS, but includes user web-based form inputs and parameters from externally triggered Runbooks.
WSDATA	Variables stored at a Worksheet.

For Outputs variables, you can specify that Outputs values are copied to either FLOWS or WSDATA variables to be transferred to the next ActionTask.

Persistent Connections and the SESSIONS Object

Most data can be transferred from the RSRemote back to the RSControl. INPUTS can be used to move lists, maps, or other non-string objects between the Content and the Assessor. However, connections and other non-serializable objects cannot be moved between components. Resolve Actions Pro provides a SESSIONS object that allows an object to be "saved" or "persisted" on an RSRemote. Later tasks that need to access this object will be executed on that RSRemote.

Persisting a Connection

The SESSIONS object can be used to retain an open connection (a "session") that is used by multiple tasks. This avoids the need to open and close the connection in each task, and allows for better modularity and reusability of ActionTasks. The workflow for persisting a connection is:

• Open a connection and save it to SESSIONS
• Execute commands using saved connection
• Close the connection and clear the SESSIONS

The SESSIONS binding is only available during automation execution, it is a reserved variable name. If you try to execute a task using SESSIONS outside of a Runbook (for example, while testing), then an exception will be thrown. The mechanics for persisting a connection are:

1.  Place an object (named "conn" in this example) into SESSIONS using the following SESSIONS.put() code. The object is kept in memory on the JVM and sets a session affinity for that RSRemote.

   SESSIONS.put(conn);
2. Later tasks using the SESSIONS object will execute on the same RSRemote. Retrieve the object using SESSIONS.get(). The affinity is stored in FLOWS. SESSIONS are unique to an execution path, and may no longer be available after a merge. If not working correctly, check FLOWS values in rscontrol.log.

   Def conn = SESSIONS.get();
3. When you are finished, remove the affinity with SESSIONS.remove(): 1 SESSIONS.remove()

Other Uses of SESSIONS

The use of the SESSIONS object is not restricted to Actions Pro Connectors. It can be used with other Groovy objects that are not serializable such as web and database connections. Note that using SESSIONS with HTML Unit, depending on the target page, can sometimes cause errors.

The SESSIONS object can also be used when an object does not need to be persisted, but tasks need to be executed on the same RSRemote. Such situations may occur when the task needs to access a particular file on the file system.

To establish a session affinity without an object, call:

SESSIONS.setAffinity();

Note that only tasks that contain the string "SESSIONS" will use the affinity, so be sure to add the string in a comment.

//SESSIONS

Always remember to clear the session when affinity is no longer needed. Also remember that the SESSIONS object, since it is maintained using FLOWS, might not persist after a merge.

SESSIONS.remove();

Runbook Variable Types

Effective Runbook development requires an understanding of data handling and operation of different variable types. The variable types are used to pass data at each stage of process and task execution.

The following diagram shows the variable availability across the various Actions Pro components.

Data Handling

Data handling refers to the use of variables, parameters, and properties to transfer data into and out of ActionTasks in Actions Pro. Proficiency in data handling is the biggest key to effective Runbook development. It differentiates simple processes from complex automations that allow for user input. Understanding data handling requires understanding the different variable types. It allows the creation of re-usable tasks that are "customizable" through data values.

The full sets of variables or objects available to Runbook components are often referred to as "bindings":

• Regular variables: INPUTS, OUTPUTS, FLOW, PARAMS
• Special variables: WSDATA, PROPERTIES, GLOBALS, RESULT
• Intrinsic variables: DATA, RAW (read-only)

Each variable is available in a variety of forms, in different parts of Actions Pro:

• WSDATA are variables, stored in the Worksheet and used to hold values to be shared with anything using the same Worksheet.
• FLOWS are Runbook variables that store data for sharing between non-consecutive ActionTasks.
• INPUTS are mapped to data from sources external to the ActionTask or data from an Actions Pro process, containing the ActionTask. They are defined in the Preprocessor but destroyed at the end of the ActionTask.
• OUTPUTS are mapped to process data types for use from other ActionTasks. They are typically created and defined in the Assessor but are actually destroyed at the beginning of the next ActionTask.
• PARAMS are variables that store initial values to Runbooks. They typically hold values from outside of the triggered Runbook.
• PROPERTIES are universal variables that can be used in any Runbook.
• GLOBALS are accessible throughout a Runbook, not specific to any execution path, and available at all times.
• RESULT is available in the ActionTask Assessor and is an object that contains the ActionTask completion, condition, severity, summary, and detail.
• RAW is available in the ActionTask Assessor and contains the raw data from Content (RSRemote).
• DATA is available in the ActionTask Assessor and is a formatted representation of RAW.

INPUTS

INPUTs are locally-defined ActionTask variables that can be used in the Preprocessor, Assessor, and task execution, and allow values to be passed into an ActionTask.

Typically, INPUT variables are defined when creating the ActionTask but you can also complement them with custom INPUT variables that only live in the current automation model.

INPUT variables can have default values that you can set when creating or editing the ActionTask. You can overwrite or redefine the default values in the automation model, or a user interacting through the Page can modify them when executing the Automation.

INPUT values can also explicitly reference values from other sources, usually the OUTPUT values from the previous ActionTask in the Runbook sequence.

You can set the INPUT value at execution time.

As an example, INPUT variables can be used as command-line arguments or in Groovy scripts.

OUTPUTS

OUTPUT variables are local output variables that you can use to pass values from the assessment of one task to the INPUTS of the following task. You can also use them to aid process-level decisions.

OUTPUT variables are defined when creating the ActionTask where you can also define a default value for the variable. You can overwrite or redefine the default value in the automation model, or a user interacting through the Page can modify them when executing the Automation.

OUTPUTs are set in the Assessor at execution time and accessed through either the Preprocessor or INPUT parameter definition. If the OUTPUT variable does not have a default value, it will be null.

PARAMS

• PARAMS allow values to be passed from external sources to Actions Pro
• PARAMS is a String Hash Map
  • Each value referenced by a key is referred to as a variable
  • Accessed and set using Groovy Map operations
• PARAMS values are automatically added
  • are primarily used to communicate external data
  • are set from internal Actions Pro values (such as PROBLEMID)
  • can be set at execution time
  • values are also inserted for each INPUT defined in an ActionTask
• PARAMS variables can be used as command-line arguments or in Groovy scripts

WSDATA

A pre-defined Actions Pro object, path independent for Runbooks.

• Accessible in all tasks
• Saved in RSSearch (Elasticsearch)
• Used for persistence across executions within a Worksheet
• Stored in RSSearch instead of kept in memory, so it should be used:
  • When data needs to be shared between separate Runbook executions
  • or a Runbook execution and a Groovy script on a wiki page.

FLOWS

Hashmap object that contains key and value pairs for storing variables that need to pass values through multiple ActionTasks.

• Accessed and set like PARAMS.
• Each task has one set of FLOWS which it gets from the previous task.
• Different paths in automation have independent sets of FLOWS.
• When paths (and values) merge, the merging task gets its FLOWS from:
  • if "Merge All", then the last task to finish
  • if "Merge Any", then the first (only) task to finish
• The scope of the FLOWS map is the execution path.

GLOBALS

The GLOBALS variable is a synchronized data structure with inherent additional overhead that stores String, List, and Map with the scope of the Runbook execution.

• Accessible throughout a Runbook, not specific to any execution path, and available at all times
• List or Map is automatically saved
• With regards to task execution, GLOBALS can only be operated by RSControl in the Preprocessor and Assessor, and not by the RSRemote working on task Content.
• String requires using a method: GLOBALS.setString("Name", "Value"):

GLOBALS.getString("Name")  
GLOBALS.getList("Name")  
GLOBALS.getMap("Name")  
GLOBALS.getNumber("abc")

PROPERTIES

Universal variables that can be used in any Runbook.

RESULT

Results object that contains the ActionTask completion, condition, severity, summary, and detail.

DATA

Parsed raw data from the Parser.

RAW

Raw results from an ActionTask.

How to Choose Variables

Choosing variables for data handling should be appropriate to scope and use.

• Use INPUTS and OUTPUTS in most cases
• Groovy scripts use maps
• As parameters to a command-line interface (CLI) use the ${} form
• Prefer FLOWS over GLOBALS, for example:
  • f there is only one path/target
  • Mutually exclusive paths end in Merge Any
• When splitting / merging:
  • Use FLOWS if each branch is to have its own set of values
  • Use GLOBALS if there is to be one set of values for the Runbook that all branches access

Reserved and Reference Variables

The following variables are reserved within Actions Pro and provide the values shown below. These variables cannot be set by the user or used as user-defined values.

The following table lists the available Preprocessor variables.

Parameter	Description
LOG	Log object used to append to RSControl log
DB	Database connection object
ESB	Object used to send Messages through RSMQ
PROCESSID	Process ID of Runbook execution
PROBLEMID	Worksheet ID
WIKI	Name of the Runbook wiki document page
PARAMS	PARAM parameter map
FLOWS	FLOW parameter map
INPUTS	INPUT parameter map
OUTPUTS	OUTPUT parameter map that contains OUTPUT variables set in the Assessor of the previous task in the Runbook sequence
GLOBALS	Object used to get and set GLOBAL variables

The following table lists the available Content (RSRemote) variables.

Parameter	Description
LOG	Log object used to append to RSControl log
REFERENCE	External System Reference, for example, Netcool ServerName:ServerSerial:Serial
PARAMS	PARAM parameter map
FLOWS	FLOW parameter map
INPUTS	INPUT parameter map
PROBLEMID	Worksheet ID
WIKI	Name of Runbook wiki document page
SESSIONS	Object used to persist a connection in a Runbook

The following table lists the available Assessor variables.

Parameter	Description
ACTIONNAME	Name of ActionTask
RAW	Raw results from an ActionTask
DATA	Parsed raw data from the Parser
DATATYPE	Type of parsed data (STRING, XML, MAP, LISTMAP)
LOG	Log object used to append to RSControl log
DB	Database connection object
ESB	Object used to send messages through RSMQ
PROCESSID	Process ID of Runbook execution
EXECUTEID	Execute ID of an ActionTask
PROBLEMID	Worksheet ID
REFERENCE	External System Reference, for example, Netcool ServerName:ServerSerial:Serial
WIKI	Name of the Runbook wiki document
INPUTS	INPUT parameter map
PARAMS	PARAM parameter map
FLOW	FLOW parameter map
RESULT	Results object that contains the ActionTask completion, condition, severity, summary, and detail
OUTPUT	OUTPUT parameter map, for assessor it will be empty
RECORD	Worksheet field hashmap to allow worksheet fields to be set
GLOBALS	Object used to get and set GLOBAL variables

Process Flow Execution

In general, RSControl runs Runbooks, while RSRemotes work on ActionTasks. Overall process execution is managed by the RSControl server, which has access to the Actions Pro Database. Individual task execution (ActionTask Content mostly) is done mainly by an RSRemote module. RSControl also operates the Preprocessor and Assessor. As the process runs through each task, RSControl executes the Preprocessor of the task before sending off to the RSRemote for Content work.

The following diagram shows the process flow execution.

The RSControl server has access to INPUT, OUTPUT, and FLOW values, as well as to GLOBAL and WSDATA variables.

1. The Preprocessor, running on RSControl, accesses:
   • OUTPUT values from previous task
   • FLOW values
   • GLOBAL and PARAM variables
2. The Preprocessor returns TARGET values.
   After the Preprocessor finishes, RSControl sends and initiates task execution at an RSRemote. RSRemote selection is controlled by the TARGET variable and QUEUE_NAME option. The RSRemote executing the task does not have access to WSDATA variables, which are only available in the Assessor.
3. The RSRemote receives:
   • Executable information (Command Line or Content scripts)
   • PROPERTIES, FLOWS, and INPUTS values
4. The RSRemote returns FLOWS, INPUTS, and RAW values.
   The return from the RSRemote is available as RAW for the Assessor, runs on the RSControl server. Before the Assessor runs, the Parser first parses commonly formatted data to return a structured object to the Assessor. The Parser also runs on the RSControl server and is shared (referenced), and thus cannot be local to an ActionTask. From the RAW value returned from Content (RSRemote), the Parser creates the DATA value formatted for use by the Assessor.
5. The Assessor thus has available to it:

• RAW and DATA values
• WSDATA variables
• INPUTS, GLOBALS, FLOWS, and PROPERTIES

1. After the Assessor runs, it sets the OUTPUT variables and the RESULT structure (condition, severity, summary, detail), which is used to evaluate condition dependency for choosing the appropriate path to follow within the process automation:
   • Condition defines the success of the ActionTask
   • Severity defines the degree of failure
   • Summary is a short output of the ActionTask
   • Detail is the assessed output of the ActionTask

All Actions Pro modules can access PROPERTIES. With regards to improved data handling of variables, a general rule to follow is to avoid FLOWS when possible, especially if FLOW values are not used after the specific ActionTask finishes (INPUTS are allowed).

Programming Practices for Actions Pro

Following best practices in programming for Runbook development can simplify troubleshooting and maintenance, as well as improve performance. Consider adopting the current programming practices from other areas when coding Groovy and other scripts in Actions Pro.

General

• All variables in Groovy scripts should be defined using the "def" keyword. This localizes the scope and helps prevent inadvertent value changes.
• Avoid using regex in Groovy scripts if simple string manipulation, such as indexOf() or substring(), is enough. This helps to improve performance.
• Use LOG.<level>() to output to log files. The levels to use from most to least verbose are: DEBUG, INFO, WARN, and ERROR. The setting in each Actions Pro component log configuration determines the highest logging level and applies to all ActionTasks (and Runbooks).
• The default level for production Actions Pro installations should be set to WARN. If troubleshooting requires, raise the level for the time required in RSCONSOLE, then return it to default.
• Use DEBUG.println() to output to the Worksheet debug tab. This only applies to ActionTasks and Runbooks running in DEBUG mode.
• When creating messages for a logging method, use a common format that includes a unique identifier to easily locate these special messages in the log output. This also helps to keep log messages brief. For example, use a string such as <enterprise> <level> <message number> <message> in which:
  • "enterprise" is a unique key identifying the message as local to a specific company
  • "level" indicates severity or purpose of the message
  • "message" number uniquely identifies the message and should be documented in a message catalog
  • "message" is the specific text giving more detail

Input and Output Parameters

• Do not use the literal substitution form of INPUTS ($INPUT{<name>}) in the Content of a Remote ActionTask. It causes a form of memory leak that compromises performance and reliability.
• To improve reusability, troubleshooting, and Runbook maintenance, ActionTasks should use only INPUTS and OUTPUTS, and avoid FLOWS, PARAMS, and WSDATA. INPUTS can have their values assigned to other variable types in the Runbook "Edit Inputs" settings. OUTPUTS can be assigned to FLOWS, PARAMS, and WSDATA in the "Edit Outputs" settings in a Runbook.
• Do not use PARAMS as the default values for the INPUT parameter in an ActionTask definition. This sets the INPUT to the value of the PARAM at the start of the Runbook and not to the value at the point of execution which complicates troubleshooting.
• Use GLOBALS only when values must be saved using targets or on merged paths. Global variable names on each merged path or for each target must be unique to be retained after merging.
• Use $PROPERTY{<XXX>} in the "Default Value" to set ActionTask property values to an INPUT.
• Use only $PROPERTY{} and constant values for default values in the ActionTask definition and use the Automation Model to set FLOWS, PARAMS, or WSDATA values.

Runbook Deployment

• Single Runbook: use single standalone Runbooks or pre-existing sub-Runbooks for small-to-medium-sized automation.
• Called Runbooks: take advantage of multi-threading in parallel execution.
• Embedded Runbooks using sub processes (sub-Runbooks): use sub-Runbooks for medium-to-large-size automation and exploit reusable components (commonly-used Runbooks).

Sub-Runbook Recommendations

• Sub-Runbooks (sub processes) let developers organize and reuse logic.
• Consider modularity in designing solutions.
• Data handling is a big concern with sub-Runbooks. An approach is to use a task before the sub-Runbook to marshal the data and validate the inputs.
• Choose the data types based on purpose.
• Use PARAMS for stand-alone sub-Runbooks and FLOWS for embedded sub-Runbooks.

ActionTask Content (Tab)

• Avoid business logic (success/failure evaluation) in the Content; assess the business logic in the Assessor. Keep it simple and clear.
• Never use the sleep() method. For delays, use the Thread .sleep() method in the Content.
• Improve performance by limiting the amount of data stored in FLOWS. Limit the use of FLOWS to where they are needed and remove FLOWS entries that are no longer needed.
• Content can be a Groovy Script for a REMOTE-type ActionTask. For other ActionTask types, except ASSESS (OS, BASH, CMD), it will act as a temporary file and can be referenced using ${INPUTFILE}. For non-groovy code, use $INPUT{<XXX>} to do a literal string substitution to pass parameters into the script/file content.
• The substitution of the value for the variable is done before creating the ${INPUTFILE}.
• Use quotes around $INPUT since the value is substituted rather than acting as a variable. Watch out for newlines in the string. See the shell script example below:

  // exception when XXX has a \n character in it
  Var mystring = "$INPUT{XXX}"
• Use try/catch blocks to handle the exceptions in code sections. Groovy errors in Content in a REMOTE-type ActionTask will still be caught and returned in the RAW variable, which may also be displayed to the user in the Detail.
• The return value from the Content groovy script will be converted to a String value. Use INPUTS to pass structured values to the Assessor from Content. For example, INPUTS"MYMAP" = 'my key': 'my value' will pass the map from the Content to the Assessor.
• Use SESSIONS to re-use connections allowing multiple commands for a given target system to be executed and assessed in separate ActionTasks. This provides better maintainability and troubleshooting and improves performance. Use of the SESSIONS object causes the Runbook ActionTasks that follow to be executed on the same RSRemote. When using SESSIONS:
  • Close the connection at the end of its use.
  • Remove the SESSIONS object entry at end of use to remove the affinity setting for a particular RSRemote.
  • Tasks that use SESSIONS can only be run as part of a Runbook.
• GLOBALS, WSDATA, and OUTPUTS cannot be used in the Content Tab. Use INPUTS for most operations when needed.
• Gateways and connectors code run from the Content of a REMOTE-type ActionTask.

ActionTask Assessor

• Each ActionTask should have its own Assessor.

• Avoid using Reference (shared) Assessors unless it makes sense to share the Assessor.

• The major role of the Assessor is to set the RESULT object values. Structuring code to set defaults, perform logical assessment, changing values, and then moving values to the RESULT object simplifies maintenance. For example:

  // Set default RESULT variables  
  def condition = "GOOD";  
  def severity = "GOOD";  
  def summary = "The uptime is ";  
  def detail = "The original uptime was $RAW\n";
  
  // Set other work variables  
  def seconds up = RAW.split()[0].to Double();  
  def hours up = (seconds up / 3600).round(2);  
  
  // Perform assessment logic  
  summary += hours up;  
  detail += "The uptime in hours is $hoursup";  
  
  // Set values in the RESULT object  
  RESULT.summary = summary;  
  RESULT.condition = condition;  
  RESULT. Severity = severity;  
  RESULT.detail = detail;  
  
  // Set other variables  
  OUTPUTS['UPTIME'] = hours up

• Use the hash map version of variables (such as INPUTSXXX?, PARAMSXXX?) and not the literal substitution version (such as $INPUT{).

• Avoid setting FLOWS directly in an Assessor. Use OUTPUTS and configure the Runbook to copy the OUTPUTS to FLOWS.

• Avoid using Thread. Sleep() in Assessors due to holds on to DB connections. Use Thread.sleep() in Content instead. Never use the Groovy sleep() method.

• Use DEBUG.println() to output to the Worksheet debug tab.

• Also try DEBUG.printInputs() or DEBUG.printOutputs().

• A connection to the Actions Pro database can be made using the DB object (java.sql.Connection) and standard JDBC methods. This should only be used for read-only access, due to the persistence mechanism. Current Worksheet data cannot be accessed through Actions Pro database and must come from RSSearch. Use the data API for access to table information in the Actions Pro database (including custom tables). entity Utile provides the mechanism for Worksheet access.

ActionTask Preprocessor

• INPUTS can be set from PARAMS in the Preprocessor but only for logical decisions or complex manipulations. Simple replacement should be done in the "Edit Inputs" of a Runbook definition.
• Preprocess can set TARGETS to allow parallel execution.
• Only PARAMS are sent to the targets for the remaining ActionTask logic, not INPUTS.
• Whenever possible, use either the default QUEUE_NAME (RSRemote) or set the QUEUE_NAME in Options, instead of placing queue_name in TARGETS.
• When used in a Runbook, consider setting TARGETS and only manipulating variables in an ASSESS-type ActionTask, deferring logic to later ActionTasks. PARAMS from the targets can be passed to OUTPUTS, used subsequently in a Runbook.
• Create a local Preprocessor for an ActionTask, avoiding Reference (shared) Preprocessors.

ActionTask Parser

Parsers allow converting from one format of data returned from the RSRemote (RAW) to a form of data more suited to use by an Assessor (DATA).

User Interface Guidelines

Use Document sections to simplify maintenance. Standard components such as headers, footers, pro forma notices, CSS, and other aspects of a user interface should be included (typically by section) from a single source document.